﻿/*******************************************************************************
 * AAEngine
 * Copyright (c) 2010 Mike Jarosch
 *
 * Original source PushButton Engine:
 * Copyright (C) 2009 PushButton Labs, LLC
 * For more information see http://www.pushbuttonengine.com
 *
 * This file is licensed under the terms of the MIT license, which is included
 * in the "MIT License.txt" file at the root directory of this SDK.
 ******************************************************************************/

namespace AAEngine.Engine.Core
{
    /// <summary>
    /// Interface for a named object that can exist in a group or set
    /// </summary>
    /// <seealso cref="PBSet"/>
    /// <seealso cref="PBGroup"/>
    /// <seealso cref="IEntity"/>
    public interface IAAObject
    {
        /// <summary>
        /// The name of the AAObject. This is set by passing a name to the initialize
        /// method after the AAObject is first created.
        /// </summary>
        /// <seealso cref="IAAObject.Initialize"/>
        string Name { get; }

        /// <summary>
        /// Since the level format references template definitions by name, and
        /// that same name is used to name the entities created by the format, it
        /// is useful to be able to look things up by a common name. So you might
        /// have Level1Background, Level2Background, Level3Background etc. but give
        /// them all the alias LevelBackground so you can look up the current level's
        /// background easily.
        /// </summary>
        /// <remarks>
        /// This is set by the second parameter to Initialize()
        /// </remarks>
        string Alias { get; }

        /// <summary>
        /// The AAGroup which owns this AAObject. If the owning group is Destroy()ed,
        /// the AAObject is Destroy()ed as well. This is useful for managing object
        /// lifespans - for instance, all the PBObjects in a level might belong
        /// to one common group for easy cleanup.
        /// </summary>
        AAGroup OwningGroup { get; set; }

        /// <summary>
        /// Initializes the AAObject, optionally assigning it a name. This should be
        /// called immediately after the AAObject is created.
        /// </summary>
        /// <param name="name">
        /// The name to assign to the AAObject. If this is null or an empty
        /// string, the AAObject will not register itself with the name manager.
        /// </param>
        /// <param name="alias">
        /// An alternate name under which this AAObject can be looked up.
        /// Useful when you need to distinguish between multiple things but refer
        /// to the active one by a consistent name.
        /// </param>
        /// <seealso cref="NameManager"/>
#if WINDOWS_PHONE || XBOX
        void Initialize();
        void Initialize(string name);
        void Initialize(string name, string alias);
#else
        void Initialize(string name = null, string alias = null);
#endif

        /// <summary>
        /// Destroys the AAObject by removing all components and unregistering it from 
        /// the name manager
        /// </summary>
        /// <remarks>
        /// AAObjects are automatically removed from any groups/sets that they
        /// are members of when they are Destroy()'ed.
        /// 
        /// Currently this will not invalidate any other references to the AAObject
        /// so the AAObject will only be cleaned up by the garbage collector if those
        /// are set to null manually.
        /// </remarks>
        void Destroy();
    }
}
